Chat - 会话

根据机器人唯一标识(机器人ID)与其进行会话,仅适用于智能对话机器人(旧版)。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

当前API暂无授权信息透出。

请求参数

名称类型必填描述示例值
InstanceIdstring

机器人唯一标识(机器人 ID)。登录云小蜜控制台,机器人详情->会话接口,查看机器人实例信息,可获得该实例 ID。

chatbot-cn-mp90s2lrk00050
Utterancestring

机器人访问者的输入

今天天气怎么样?
SessionIdstring

会话 ID,用于标识一个访问者的会话和保持上下文信息。对于一个新的访问者,首次调用 Chat 接口时无需传递此字段,机器人会开启一个会话,并在 Chat 接口的响应中返回该会话的 SessionId。对于该访问者的后续轮次的会话,调用 Chat 接口时传递当前会话的 SessionId,机器人即可基于 SessionId 继续该轮次会话。长度限制是 64 个字符

9c6ebdc6e66f46ecadab3434314f6959
KnowledgeIdstring

知识库中知识标题的 ID。若指定此 ID,那么机器人会直接返回指定知识标题的答案

30002406051
SenderIdstring

访问者 ID。用于识别当前会话中的用户

custumer_123456
SenderNickstring

当前会话中访问的昵称

用户123456
IntentNamestring

对话流中意图名称。 若指定此名称,机器人会直接进入此意图做问答

查天气意图
Perspectivearray

视角编码数组,用于调用同一知识标题下不同视角的答案。如:Perspective=["FZJBY3raWr"]。使用 SDK 时以 SDK 中定义的参数为准

string

视角编码

FZJBY3raWr
VendorParamstring

是一个 JSON 格式的用户自定义参数集,可以传入用户自定义的参数到各对话引擎

{"phone":123456789}
SandBoxboolean

测试、正式环境标识,默认为正式环境。

  • true:测试环境,仅限测试使用,生产使用有不稳定、QPS 限制等风险。
  • false:正式环境
true
AgentKeystring

业务空间 key,不设置则访问默认业务空间,key 值在主账号业务管理页面获取

ac627989eb4f8a98ed05fd098bbae5_p_beebot_public

返回参数

名称类型描述示例值
object
QuerySegListarray

query 的分词结果,可能为空

query的分词结果,可能为空string

问题的分词数组,如 [ "查", "天气" ]

天气
Messagesarray<object>

消息的列表

消息的列表object

消息

Knowledgeobject

当 AnswerType 为 Knowledge 时,此字段包含机器人返回的 Knowledge 对象

HitStatementstring

命中语句

公积金
Summarystring

命中问题的简介

公积金提取
RelatedKnowledgesarray<object>

关联知识列表

RelatedKnowledgesobject

关联知识

KnowledgeIdstring

知识关联知识的 ID

735899
Titlestring

知识的关联知识的标题

公积金查询
Categorystring

知识类目

公积金
Titlestring

命中问题的标题

公积金提取
Contentstring

命中问题的内容

公积金提取,请在首页搜索公积金提取,提交办事的表单
AnswerSourcestring

区分答案类型。 KnowledgeBas:知识库;

KnowledgeBase
Idstring

命中问题在知识库中的 ID

735898
Scoredouble

分数

0.998
ContentTypestring

纯文本或富文本答案的标识

枚举值:
  • PLAIN_TEXT纯本文
  • RICH_TEXT富文本
PLAIN_TEXT
Textobject

当 AnswerType 为 Text 时,此字段包含机器人返回的 Text 对象

HitStatementstring

命中语句

查天气
DialogNamestring

当 AnswerSource 为 BotFramework 时,此字段返回对话单元名称

示例_查天气
ArticleTitlestring

当 AnswerSource 为 MACHINE_READ 时,此字段返回命中文章标题

备案十一
AnswerSourcestring

区分答案类型

枚举值:
  • TABLEQA表格问答
  • COMMANDS系统指令
  • SENSITIVE_WORD 全局敏感词
  • BotFramework对话工厂
  • MACHINE_READ机器阅读
  • ChitChat闲聊
  • NO_ANSWER无答案
BotFramework
Slotsarray<object>

当 AnswerSource 为 BotFramework 时,此字段返回专有名词列表

Slotsobject

槽位信息

Valuestring

具体值

北京
Originstring

原始值

北京
Namestring

名称

查天气意图.city
Hitboolean

是否命中

false
NodeNamestring

当 AnswerSource 为 BotFramework 时,此字段返回节点名称

示例_查天气.查天气填槽.__city
IntentNamestring

当 AnswerSource 为 BotFramework 时,此字段返回意图名称

查天气意图
MetaDatastring

元数据

[[{\"columnName\":\"姓名\",\"stringValue\":\"王珊珊\"}]]
ExternalFlagsobject

当 AnswerSource 为 BotFramework 时,此字段返回透传参数

Extobject

此字段返回透传参数

{ "MATCHED_INTENT_SOURCE": "", "INTENT_ID": 724414, "IntentName": "查天气意图", "INTENT_DETAIL": "[我想|我要]查天气", "LGF_EXPRESSION": "[我想|我要]查天气", "IS_SESSION_FINISHED": false, "DsScore": 100.0, "DIALOG_ID": "299034", "FINISH_LABEL": false, "MODULE_START": false, "INTENT_NAME": "查天气意图", "INTENT_SOURCE": "Lgf", "DIALOG_NAME": "示例_查天气" }
UserDefinedChatTitlestring

自定义闲聊主题标题

问候
Contentstring

文本消息的内容

请问您要查哪里的天气?
NodeIdstring

当 AnswerSource 为 BotFramework 时,此字段返回节点 ID

1410-c7a72a78.__city
Scoredouble

分数

100.0
ContentTypestring

纯文本或富文本答案的标识

枚举值:
  • PLAIN_TEXT纯本文
  • RICH_TEXT富文本
PLAIN_TEXT
Commandsobject

指令参数,如转人工指令的转人工技能组

{ "sysToAgent": "{\"skillGroup\":\"12\"}" }
ResponseTypestring

当 AnswerSource 为 BotFramework,ResponseType 为 SSML 时,表示命中对话工厂交互式填槽;否则字段不存在

SSML
Recommendsarray<object>

当 AnswerType 为 Recommend 时,此字段包含机器人返回的 Recommend 的列表

Recommendobject

recommend 对象

KnowledgeIdstring

澄清的知识 ID

4548
Titlestring

澄清内容,可能是 图谱问答的实体、 知识问答的知识标题、 表格问答的列值

测试纯文本
AnswerSourcestring

澄清来源的标识

枚举值:
  • BotFramework对话工厂
  • KnowledgeFAQ
KNOWLEDGE
Scoredouble

推荐内容的分数,当 AnswerSource 为 KNOWLEDGE 时,此字段有值

0.46
AnswerTypestring

本条消息的类型

枚举值:
  • Recommend澄清或者反问
  • Text文本
  • Knowledge知识库知识直出
Text
AnswerSourcestring

当 AnswerType 为 Recommend 时,此字段表示推荐的答案来源

枚举值:
  • INTENT_FAQ_CLARIFYFAQ和对话工厂混合澄清
  • TABLEQA表格问答
  • KNOWLEDGEFAQ
  • BotFramework对话工厂
KNOWLEDGE
VoiceTitlestring

语音场景,澄清内容

请问你说的是公积金查询,还是公积金提取
Titlestring

在线场景,反问标题

请问您想咨询的是哪个投保年龄区间呢?
RequestIdstring

请求 ID

A2315C4B-A872-5DEE-9DAD-D73B194A4AEC
SessionIdstring

本次会话的 ID

a6f216a0685c4c8baa0e8beb6d5ec6db
MessageIdstring

本条会话应答消息的 ID

A2315C4B-A872-5DEE-9DAD-D73B194A4AEC

Ext 字段说明

AnswerSource=BotFramework 时:

字段名类型描述
MATCHED_ENTRY_NAMEString命中的触发节点名称
MATCHED_INTENT_SOURCEString命中的触发节点意图来源
INTENT_IDLong命中的意图 ID
IntentNameString与 INTENT_NAME 相同
INTENT_DETAILString意图命中的方式细节,主要在 INTENT_SOURCE=Similarity 或者 Lgf 的时候有用,当为 Similarity 时,这个字段的值就是匹配的意图话术,当为 Lgf 时,这个字段的值就是匹配的 Lgf 语法
IS_SESSION_FINISHEDBoolean会话是否完结标志
DsScoreString命中对话流的分数
DIALOG_IDString对话流 ID
FINISH_LABELBoolean回复节点是否被标记为完结节点,由业务定义,常用于业务统计
MODULE_STARTBoolean是否为对话流开启意图节点
INTENT_NAMEString命中的意图名称
INTENT_SOURCEString意图识别命中的来源方法,包括:Simialrity - 相似度匹配方法,Lgf - LGF 语法匹配方法,Classify - 有监督模型方法
DIALOG_NAMEString对话流名称
DS_REPORTMap对话流变量配置中,勾选为“输出至报表”的变量 key value 数据
TASK_IDString异步服务返回的任务 ID

响应报文:

FAQ 问答-直出
{
  "QuerySegList": [
    "测试",
    "富文",
    "本"
  ],
  "Messages": [
    {
      "Knowledge": {
        "Score": 100.0,
        "Category": "第一个类目",
        "ContentType": "RICH_TEXT",
        "AnswerSource": "KnowledgeBase",
        "Content": "<p>富文本答案啊</p>",
        "Summary": "富文本答案啊",
        "Title": "测试富文本",
        "Id": "4549"
      },
      "AnswerType": "Knowledge"
    }
  ],
  "RequestId": "1b8b19de-7e6d-4e45-b7f1-9daca21af8b0",
  "SessionId": "1234",
  "MessageId": "1b8b19de-7e6d-4e45-b7f1-9daca21af8b0"
}
FAQ 问答-澄清
{
  "QuerySegList": [
    "文本"
  ],
  "Messages": [
    {
      "AnswerSource": "KNOWLEDGE",
      "Recommends": [
        {
          "Score": 46.0,
          "Title": "测试纯文本",
          "KnowledgeId": "4548"
        }
      ],
      "AnswerType": "Recommend"
    }
  ],
  "RequestId": "5af5d5f9-76b1-45e9-8003-fcd07ab9a5e4",
  "SessionId": "1234",
  "MessageId": "5af5d5f9-76b1-45e9-8003-fcd07ab9a5e4"
}
对话工厂直出
{
  "QuerySegList": [
    "查",
    "天气"
  ],
  "Messages": [
    {
      "Text": {
        "Ext": {
          "MATCHED_ENTRY_NAME": "intentWithout_city",
          "MATCHED_INTENT_SOURCE": "",
          "INTENT_ID": 724414,
          "BOT_ANSWER_SOURCE": "Lgf",
          "IntentName": "查天气意图",
          "INTENT_DETAIL": "[我想|我要]查天气",
          "LGF_EXPRESSION": "[我想|我要]查天气",
          "IS_SESSION_FINISHED": false,
          "DsScore": 100.0,
          "DIALOG_ID": "299034",
          "FINISH_LABEL": false,
          "MODULE_START": false,
          "INTENT_NAME": "查天气意图",
          "INTENT_SOURCE": "Lgf",
          "DIALOG_NAME": "示例_查天气"
        },
        "ContentType": "PLAIN_TEXT",
        "NodeName": "示例_查天气.查天气填槽.__city",
        "AnswerSource": "BotFramework",
        "Slots": [
          {
            "Origin": "",
            "Hit": false,
            "Value": "",
            "Name": "查天气意图.city"
          }
        ],
        "Score": 100.0,
        "DialogName": "示例_查天气",
        "IntentName": "查天气意图",
        "Content": "请问您要查哪里的天气?",
        "NodeId": "1410-c7a72a78.__city",
        "ExternalFlags": {
          
        }
      },
      "AnswerType": "Text"
    }
  ],
  "RequestId": "dc6757ef-9d03-4255-92ec-d262752a88ed",
  "SessionId": "1234",
  "MessageId": "dc6757ef-9d03-4255-92ec-d262752a88ed"
}
对话工厂澄清
{
  "QuerySegList": [
    "公积金"
  ],
  "Messages": [
    {
      "VoiceTitle": "请问你说的是公积金查询,还是公积金提取",
      "AnswerSource": "BotFramework",
      "Recommends": [
        {
          "Score": 0.656,
          "AnswerSource": "BotFramework",
          "Title": "公积金查询",
          "KnowledgeId": "735899"
        },
        {
          "Score": 0.634,
          "AnswerSource": "BotFramework",
          "Title": "公积金提取",
          "KnowledgeId": "735900"
        }
      ],
      "AnswerType": "Recommend"
    }
  ],
  "RequestId": "ab6be8af-cee4-40c3-9919-2ac7461d7d98",
  "SessionId": "123",
  "MessageId": "ab6be8af-cee4-40c3-9919-2ac7461d7d98"
}
意图、FAQ 混合澄清
{
  "QuerySegList": [
    "公积金"
  ],
  "Messages": [
    {
      "VoiceTitle": "请问你说的是公积金查询,还是住房公积金在个人所得税税前扣除的具体规定是什么?",
      "AnswerSource": "INTENT_FAQ_CLARIFY",
      "Recommends": [
        {
          "Score": 0.656,
          "AnswerSource": "BotFramework",
          "Title": "公积金查询",
          "KnowledgeId": "735899"
        },
        {
          "Score": 0.47410887479782104,
          "Category": "税务-12366&680 条-税款计算-居民个人取得综合所得-个人所得税专项扣除",
          "AnswerSource": "KNOWLEDGE",
          "Title": "住房公积金在个人所得税税前扣除的具体规定是什么?",
          "KnowledgeId": "7049"
        }
      ],
      "AnswerType": "Recommend"
    }
  ],
  "RequestId": "08d6bb1c-5394-4836-8e4a-86c07e7729b1",
  "SessionId": "123",
  "MessageId": "08d6bb1c-5394-4836-8e4a-86c07e7729b1"
}
闲聊
{
  "QuerySegList": [
    "你好"
  ],
  "Messages": [
    {
      "Text": {
        "ContentType": "PLAIN_TEXT",
        "AnswerSource": "ChitChat",
        "HitStatement": "你好",
        "Content": "哔~哔~哔~,我来了"
      },
      "AnswerType": "Text"
    }
  ],
  "RequestId": "8f267d8c-c118-4d6a-9ba1-2a5bdc720fed",
  "SessionId": "1234",
  "MessageId": "8f267d8c-c118-4d6a-9ba1-2a5bdc720fed"
}
全局敏感词
{
  "QuerySegList": [
    "查",
    "天气"
  ],
  "Messages": [
    {
      "Text": {
        "ContentType": "PLAIN_TEXT",
        "AnswerSource": "SENSITIVE_WORD",
        "Content": "您说的这个问题我不能回答您,您可以尝试询问其他问题"
      },
      "AnswerType": "Text"
    }
  ],
  "RequestId": "961d4187-e2e7-4463-8063-a4c79c912227",
  "SessionId": "1234",
  "MessageId": "961d4187-e2e7-4463-8063-a4c79c912227"
}
转人工
全局转人工
{
  "QuerySegList": [
    "人工"
  ],
  "Messages": [
    {
      "Text": {
        "ContentType": "PLAIN_TEXT",
        "AnswerSource": "COMMANDS",
        "Content": "正在为您转接人工客服",
        "Commands": {
          "sysToAgent": "{\"skillGroup\":\"12\"}"
        }
      },
      "Knowledge": {
        
      },
      "Type": "Text",
      "AnswerType": "Text"
    }
  ],
  "RequestId": "1ad8733a-7180-4e3b-a969-96f47d774256",
  "SessionId": "123",
  "MessageId": "fbbe0230-af14-4850-8f59-2ff60dfbf773"
}
触发对话工厂意图转人工
{
  "QuerySegList": [
    "转",
    "人工"
  ],
  "Messages": [
    {
      "Text": {
        "Ext": {
          "MATCHED_ENTRY_NAME": "转人工",
          "MATCHED_INTENT_SOURCE": "",
          "INTENT_ID": 8454,
          "BOT_ANSWER_SOURCE": "Similarity",
          "intentName": "转人工",
          "DsScore": 100.0,
          "INTENT_DETAIL": "转人工",
          "LGF_EXPRESSION": "转人工",
          "IS_SESSION_FINISHED": true,
          "dsScore": 100.0,
          "DIALOG_ID": "2529",
          "FINISH_LABEL": false,
          "IntentName": "转人工",
          "MODULE_START": true,
          "INTENT_NAME": "转人工",
          "INTENT_SOURCE": "Similarity",
          "DIALOG_NAME": "公积金转人工"
        },
        "ContentType": "PLAIN_TEXT",
        "NodeName": "公积金转人工.回复信息",
        "AnswerSource": "BotFramework",
        "Score": 100.0,
        "DialogName": "公积金转人工",
        "IntentName": "转人工",
        "Content": "这是转人工的回复",
        "Commands": {
          "sysToAgent": "{\"skillGroup\":\"8\",\"ext\":\"123\"}"
        },
        "NodeId": "i073y198",
        "ExternalFlags": {
          
        }
      },
      "Type": "Text",
      "AnswerType": "Text"
    }
  ],
  "RequestId": "1ad8733a-7180-4e3b-a969-96f47d774256",
  "SessionId": "123",
  "MessageId": "590f0434-030a-4de2-8212-bf1a96e0c687"
}
无答案
{
  "QuerySegList": [
    "公积金",
    "贷款"
  ],
  "Messages": [
    {
      "Text": {
        "ContentType": "PLAIN_TEXT",
        "AnswerSource": "NO_ANSWER",
        "Content": "我还没有学会这个问题,已经记录会尽快学习为您解答,请尝试询问我其他问题"
      },
      "AnswerType": "Text"
    }
  ],
  "RequestId": "1ad8733a-7180-4e3b-a969-96f47d774256",
  "SessionId": "1234",
  "MessageId": "1ad8733a-7180-4e3b-a969-96f47d774256"
}
机器阅读 [非标,依赖开启文档问答能力]
{
    "QuerySegList":[
        "项目",
        "备案"
    ],
    "Messages":[
        {
            "Type":"Text",
            "AnswerType": "Text",
            "Text":{
                "AnswerSource":"MACHINE_READ",
                "ArticleTitle":"备案十一",
                "Content":"四、申请接收:
申请方式:网上申请
联系电话:0571-8705272487052837
办公地址:五、办理基本流程:
1、项目单位登录浙江政务服务网(http://www.zjzwfw.gov.cn)进行法人用户
注册。
2、项目单位使用法人用户账号登录浙江政务服务网投资项目在线审批监
管平台(http://tzxm.zjzwfw.gov.cn)(以下简称在线平台)。
3、项目单位选择在线平台“项目登记”中的“备案类登记”栏目,进入
备案系统。
4、填报项目备案信息
5、提交项目备案信息表,完成项目赋码
6、提交声明,完成项目备案
流程图:http://zjqlk.oss-cn-hangzhou.aliyuncs.com/c/5/53"
            }
        }
    ],
    "RequestId":"089abc58-e9ab-4aa8-86a8-70fc9d8cf0fb",
    "SessionId":"123",
    "MessageId":"089abc58-e9ab-4aa8-86a8-70fc9d8cf0fb"
}
表格问答直出[非标,依赖开启 Tableqa 能力]
{
  "QuerySegList": [
    "王珊珊",
    "的",
    "成绩"
  ],
  "Messages": [
    {
      "Text": {
        "ContentType": "PLAIN_TEXT",
        "AnswerSource": "TABLEQA",
        "Content": "姓名是王珊珊的成绩是不及格"
      },
      "AnswerType": "Text"
    }
  ],
  "RequestId": "c09d1913-dd8d-4a45-b8bd-e45e4fcf872b",
  "SessionId": "123",
  "MessageId": "c09d1913-dd8d-4a45-b8bd-e45e4fcf872b"
}
表格问答反问[非标,依赖开启 Tableqa 能力]
{
  "QuerySegList": [
    "收益率",
    "大于",
    "4",
    "的",
    "产品"
  ],
  "Messages": [
    {
      "AnswerSource": "TABLEQA",
      "Title": "请选择投资时间:",
      "Recommends": [
        {
          "Title": "1907"
        },
        {
          "Title": "31"
        },
        {
          "Title": "365"
        }
      ],
      "AnswerType": "Recommend"
    }
  ],
  "RequestId": "abef84e0-8d08-4d80-9dfb-2e958e0833ad",
  "SessionId": "1234",
  "MessageId": "abef84e0-8d08-4d80-9dfb-2e958e0833ad"
}

示例

正常返回示例

JSON格式

{
  "QuerySegList": [
    "天气"
  ],
  "Messages": [
    {
      "Knowledge": {
        "HitStatement": "公积金",
        "Summary": "公积金提取",
        "RelatedKnowledges": [
          {
            "KnowledgeId": "735899",
            "Title": "公积金查询"
          }
        ],
        "Category": "公积金",
        "Title": "公积金提取",
        "Content": "公积金提取,请在首页搜索公积金提取,提交办事的表单",
        "AnswerSource": "KnowledgeBase",
        "Id": "735898",
        "Score": 0.998,
        "ContentType": "PLAIN_TEXT"
      },
      "Text": {
        "HitStatement": "查天气",
        "DialogName": "示例_查天气",
        "ArticleTitle": "备案十一",
        "AnswerSource": "BotFramework",
        "Slots": [
          {
            "Value": "北京",
            "Origin": "北京",
            "Name": "查天气意图.city",
            "Hit": false
          }
        ],
        "NodeName": "示例_查天气.查天气填槽.__city",
        "IntentName": "查天气意图",
        "MetaData": "[[{\\\"columnName\\\":\\\"姓名\\\",\\\"stringValue\\\":\\\"王珊珊\\\"}]]",
        "ExternalFlags": {
          "test": "test",
          "test2": 1
        },
        "Ext": {
          "MATCHED_INTENT_SOURCE": "",
          "INTENT_ID": 724414,
          "IntentName": "查天气意图",
          "INTENT_DETAIL": "[我想|我要]查天气",
          "LGF_EXPRESSION": "[我想|我要]查天气",
          "IS_SESSION_FINISHED": false,
          "DsScore": 100,
          "DIALOG_ID": "299034",
          "FINISH_LABEL": false,
          "MODULE_START": false,
          "INTENT_NAME": "查天气意图",
          "INTENT_SOURCE": "Lgf",
          "DIALOG_NAME": "示例_查天气"
        },
        "UserDefinedChatTitle": "问候",
        "Content": "请问您要查哪里的天气?",
        "NodeId": "1410-c7a72a78.__city",
        "Score": 100,
        "ContentType": "PLAIN_TEXT",
        "Commands": {
          "sysToAgent": "{\"skillGroup\":\"12\"}"
        },
        "ResponseType": "SSML"
      },
      "Recommends": [
        {
          "KnowledgeId": "4548",
          "Title": "测试纯文本",
          "AnswerSource": "KNOWLEDGE",
          "Score": 0.46
        }
      ],
      "AnswerType": "Text",
      "AnswerSource": "KNOWLEDGE",
      "VoiceTitle": "请问你说的是公积金查询,还是公积金提取",
      "Title": "请问您想咨询的是哪个投保年龄区间呢?"
    }
  ],
  "RequestId": "A2315C4B-A872-5DEE-9DAD-D73B194A4AEC",
  "SessionId": "a6f216a0685c4c8baa0e8beb6d5ec6db",
  "MessageId": "A2315C4B-A872-5DEE-9DAD-D73B194A4AEC\n"
}

错误码

访问错误中心查看更多错误码。

变更历史

变更时间变更内容概要操作
2023-04-27OpenAPI 入参发生变更查看变更详情

常见问答错误

第三方服务错误

第三方服务错误是由于在 FAQ 或对话工厂中配置了第三方服务的接口,在问答命中配置的条件或话术时,会调用对应的第三方服务。如果该服务调用错误,则会提示“Third party interface error”,具体协议如下。

响应参数说明

字段名称字段含义
RequestId请求 ID
HostId云小蜜主机 ID
Code错误码,第三方服务错误的错误码为“Third party interface error”
Message错误说明

响应参数示例

{
    "RequestId": "A805905D-B20C-57C9-8793-EAF98FBD8F84",
    "HostId": "chatbot.cn-shanghai.aliyuncs.com",
    "Code": "Third party interface error",
    "Message": "第三方接口错误. HTTP 请求出现 IOException 异常,可能由网络链接超时,服务端未响应或其他配置问题导致, Url 信息: https://example.com/order/create",
    "Recommend": "https://next.api.aliyun.com/troubleshoot?q=Third party interface error&product=Chatbot"
}